Pular para o conteúdo principal

Exemplo de Evento Webhook

Esta página mostra a estrutura completa dos eventos enviados para o seu webhook​

Com que frequência os eventos são enviados?​

Os eventos são enviados em tempo real, assim que o SDK detecta uma entrada de um usuário em uma área monitorada. A latência típica é de poucos segundos, dependendo da conectividade do dispositivo.

O envio de eventos segue dessa forma:

  • Dispositivo entrou na área de interesse (Cell ID monitorado), enviamos o evento de EVENT_IN
  • Se o dispositivo permanecer na área, não enviamos novos eventos de entrada dentro de 24 horas.
  • Quando o evento sair da área e tivermos confirmação disso via sistema, vamos registrar essa saída.
  • Caso o usuário volte a área do último cell_id configurado, vamos fazer envio novamente do EVENT_IN mesmo que ainda esteja na janela de 24 horas.

Estrutura do Evento​

Quando um usuário entra ou sai de uma área de interesse, um evento é enviado via POST para o seu endpoint webhook no formato JSON.

Exemplo Completo​

{
  "mm": 1220290060,
  "cell_id": "8881839825fffff",
  "event_type": "EVENT_IN",
  "event_duration": -1,
  "created_at": 1767623650044,
  "brand": "apple",
  "model": "iPhone14,2",
  "cfray": "55e5fg9e5ege4hgh-POA",
  "origin": "beacon",
  "adv_key": "com.grouplinknetwork.glconsumointeligente.sanasainteligente",
  "os": "iOS",
  "os_version": "26.1",
  "package_name": "com.grouplinknetwork.glconsumointeligente.sanasainteligente"
}

Descrição dos Campos​

Campos Principais​

CampoTipoDescriçãoExemplo
mmnumberIdentificador único do mobile (hash do device ID)1220290060
cell_idstringIdentificador da célula H3 onde o evento ocorreu"8881839825fffff"
event_typestringTipo do evento: EVENT_IN (entrada)"EVENT_IN"
event_durationnumberDuração do evento em milissegundos. -1 para eventos de entrada-1
created_atnumberTimestamp Unix em milissegundos de quando o evento foi criado1767623650044

Informações do Dispositivo​

CampoTipoDescriçãoExemplo
brandstringMarca do dispositivo"apple", "samsung", "xiaomi"
modelstringModelo do dispositivo"iPhone14,2", "SM-G998B"
osstringSistema operacional do dispositivo"iOS", "Android"
os_versionstringVersão do sistema operacional"26.1", "14.0"

Campos Técnicos​

CampoTipoDescriçãoExemplo
cfraystringIdentificador de rastreamento CloudFlare (para debug)"55e5fg9e5ege4hgh-POA"
originstringOrigem do sinal: "beacon", "gps", "network""beacon"
adv_keystringChave de advertising/identificação do beacon"com.app.example"
package_namestringPackage name do aplicativo que gerou o evento"com.suaempresa.seuapp"

Tipos de Eventos​

EVENT_IN - Entrada na Área​

Disparado quando o usuário entra em uma área de interesse (Cell ID monitorado).

{
  "event_type": "EVENT_IN",
  "event_duration": -1,
  "cell_id": "8881839825fffff",
  ...
}

Características:

  • event_type: sempre "EVENT_IN"
  • event_duration: sempre -1 (ainda não há duração pois o usuário acabou de entrar)

Exemplos de Uso​

Exemplo 1: Evento de Entrada (iOS)​

{
  "mm": 1220290060,
  "cell_id": "88a8100ecdfffff",
  "event_type": "EVENT_IN",
  "event_duration": -1,
  "created_at": 1767623650044,
  "brand": "apple",
  "model": "iPhone15,3",
  "cfray": "abc123def456-GRU",
  "origin": "beacon",
  "adv_key": "com.mango.nexopdf",
  "os": "iOS",
  "os_version": "17.2",
  "package_name": "com.Dataoris.app"
}

Interpretação: Um usuário com iPhone 15 Pro entrou na célula 88a8100ecdfffff usando o app com package name com.Dataoris.app.

Processamento dos Eventos​

Recomendações​

  1. Validação: Sempre valide a estrutura do JSON recebido
  2. Idempotência: Use o campo created_at + mm + event_type para evitar processar eventos duplicados
  3. Assíncrono: Retorne 200 OK imediatamente e processe o evento de forma assíncrona
  4. Logging: Registre todos os eventos recebidos para análise e debug

Exemplo de Validação (Node.js)​

function validateEvent(event) {
  const requiredFields = ["mm", "cell_id", "event_type", "created_at"];

  for (const field of requiredFields) {
    if (!(field in event)) {
      throw new Error(`Campo obrigatório ausente: ${field}`);
    }
  }

  return true;
}

Conversão de Timestamps​

O campo created_at está em formato Unix timestamp (milissegundos).

JavaScript/Node.js​

const date = new Date(event.created_at);
console.log(date.toISOString()); // "2026-01-05T12:34:10.044Z"

Python​

from datetime import datetime

timestamp_ms = 1767623650044
date = datetime.fromtimestamp(timestamp_ms / 1000)
print(date.isoformat())  # "2026-01-05T12:34:10.044"

PHP​

$timestamp_ms = 1767623650044;
$date = new DateTime('@' . ($timestamp_ms / 1000));
echo $date->format('Y-m-d H:i:s');

Campos que Podem Variar​

Alguns campos podem ter valores diferentes dependendo do contexto:

origin​

  • "beacon": Detecção via IoT Grouplink
  • "beacon-gps": Detecção via gps IoT Grouplink
  • "gps": Detecção via GPS

brand​

  • "apple": Dispositivos iOS (iPhone, iPad)
  • "samsung": Dispositivos Samsung
  • "xiaomi": Dispositivos Xiaomi
  • "motorola": Dispositivos Motorola
  • Entre outros fabricantes Android

os​

  • "iOS": Sistema operacional da Apple
  • "Android": Sistema operacional Android

Perguntas Frequentes​

O campo mm é único por dispositivo?​

Sim, o mm é um hash do device ID e representa um dispositivo específico de forma pseudônima.

O que fazer se receber eventos duplicados?​

Implemente deduplicação usando a combinação de mm + created_at + event_type + cell_id.

Os eventos são enviados em tempo real?​

Sim, os eventos são enviados em tempo real assim que detectados pelo SDK. Pode haver uma latência de poucos segundos dependendo da conectividade do dispositivo.

Como sei qual usuário específico gerou o evento?​

O campo mm é um identificador pseudônimo. Se você precisar associar a um usuário específico do seu sistema, você pode implementar identificação de usuário no SDK (veja documentação do SDK).

Próximos Passos​

Suporte​

Dúvidas sobre a estrutura dos eventos? Entre em contato: